一文详解 API 设计最佳实践

-     前言    -

良好设计的API = 快乐的程序员 😃。

应用程序接口（API）是一种接口，它让应用程序可以轻松地使用另一个应用程序的数据和资源，API 对于一个产品或公司的成功至关重要。

如果没有 API，你大部分喜欢的软件今天就不会存在。例如，Google Maps API 可以让你在 app 或 Web 应用中使用 Google Maps。如果没有它，你将不得不设计和开发自己的地图数据库。这样的话，在地图上显示一个位置需要花费多少时间？

-     为什么要使用 API？    -

为什么要使用 API？

1. API 可以让外部应用访问您的资源
2. API 扩展了应用程序的功能
3. API 允许开发者重用应用逻辑
4. API 是独立于平台的，它们传递数据不受请求平台的影响

在大多数实际场景中，数据模型 已经存在，但由于我们将讨论 API 设计最佳实践，我将从头开始说起。

-     数据建模与结构化    -

以 API 为中心对您的数据进行建模，是设计易于创建、维护和更新 API 的第一步

在设计 API 时，尽量考虑使用通用的术语，而不是使用内部的复杂业务术语，因为这些术语在公司外可能不为人所知。你的 API 可能会对外开放，以允许外部开发人员使用你的 API 开发他们自己的应用。通过使用通用术语，你可以确保使用 API 的开发人员易于了解你的 API，并能快速上手。

假设到你正在建立一个门户网站，让用户点评不同作者的书籍。你的公司可能会使用特定的术语，如创作者、创作、系列等来指代图书作者、书籍和系列。但为了简单起见，并方便外部应用开发者使用你的 API，使用通用的概念而不是公司特定的术语来创建 API 路径。

https://api.domain.com/authors
 https://api.domain.com/authors/{id}/books

这有助于新的开发人员快速了解你的 API 是什么，以及如何遍历你的数据模型。

-     编写面向资源的 API    -

应用程序需要访问你的资源。维护一个资源层次结构可以帮助你更好地构建 API。资源层次结构是指路径中的每个节点，它由一个集合或一个资源组成。

资源可以是一个单一的数据，例如，上面例子中的作者简介。

集合是指一个资源的集合，在我们的例子中，它可以是一个作者所写的书的列表。

合适的资源层次结构可以是：

Base Path -> 作者 (集合) -> profile (资源)
Base Path -> 作者 (集合) -> 书 (集合) -> 书 (资源)

层次结构需要保持一致，以确保开发人员在将其应用程序接入 API 时遇到的问题最少。

为了保持简单性和一致性，这里有一些指导原则可以帮助你：

1. 命名集合和资源时使用美式英语（例如：color 而不是 colour）
2. 避免拼写错误
3. 使用更简单、更常用的词来保持清晰，例如 delete 而不是 remove
4. 如果你使用的资源与其他 API 使用的资源相同，请使用相同的术语以保持一致。
5. 对集合使用复数形式（例如：authors、books 等）。

-     RESTful 接口    -

HTTP 形式的 API 最广泛接受的标准是 REST(Representational State Transfer)。它基本上意味着每个 URL 代表一个对象。

API 目的可以是以下之一：

1. 创建数据 Create
2. 读取数据 Read
3. 更新数据 Update
4. 删除数据 Delete

CRUD！猜对了!

API 通过使用一组 HTTP 命令来处理，这些命令定义了请求的性质和它应该做什么。

GET 从 API 中检索数据。它要求从 API 中获取数据的表示。GET请求可以包含查询参数，以过滤从API接收的结果。

POST 向 API 提交一条记录，该记录将在数据库中创建一个资源。

PUT 一般用于更新服务器上的现有资源。

DELETE 从服务器上删除一个资源。

-     API 版本控制    -

应用程序和 API 的生命周期越长，应用和 API 对用户的承诺就越大。在某个时间点上，你的 API 将需要修改，因为你无法预见随着需求和业务政策而发生的变化。

因此需要对 API 进行更改。但是 API 可能已经有一个或多个开发者在使用了，所以，重要的是，你所做的更改不会破坏你的合作伙伴开发者的应用。

-     了解主要和次要更新    -

小版本升级（Minor）：当变更不会破坏客户端应用程序的运行时，可以使用小版本升级，例如添加可选字段或支持附加参数。这时候你可以为你的 API 增设小版本。

大版本升级（Major）：是那些肯定会破坏现有客户端应用的版本，比如在请求参数中添加一个新的必需参数，或改变返回结果中的字段。

可以通过多种方式来对 API 进行版本控制。

最常见的方法是将版本包含在 URI 中。

https://api.domain.com/v1.0/authors

另外一种方法是使用基于日期的版本控制。URI 中包括将版本发布日期。应用程序开发人员可以很方便了解 API 更改的频率。

https://api.domain.com/2020-06-15/authors

另一种方法是在请求标头中包含 API 版本。

https://api.domain.com/authors
 x-api-version：v1

最推荐和接受的版本控制方式是，在URI 中使用版本名称。

-     分页    -

在数据量越来越大的世界里，不可能在一个屏幕上同时显示所有的数据。所以，让用户在再次请求数据之前，先取到一定数量的结果，这一点很重要。这就是所谓的分页，返回的数据集叫做页面。

建议你在请求和返回结果中使用特定的术语来启用 API 中的分页功能。这些术语有

1. STRING page_token（在请求中发送）
2. STRING next_page_token（由 API 返回）
3. INT page_size（在请求中发送）

page_token 请求 API 需要返回哪个页面。这通常是一个字符串。对于第一次API调用，page_token = "1"

page_size 定义了返回结果中应该返回多少条记录。例如page_size = 100，在API调用中最多返回100条记录。

next_page_token 定义了翻页的下一个 token。如果在page_token = "1" 之后有额外的数据，返回的值是应当是  next_page_token="2"

如果没有更多的数据可用，而且用户已经到达数据的终点，则返回一个空白值 next_page_token="" 。

这些就是设计 API 的最佳实践。它让你的 API 更健壮、简洁并易于与其他应用程序集成。

请记住。

良好设计的API = 快乐的程序员 😃。

作者：Varun Joshi

来源：

https://codeburst.io/best-practices-api-design-61d4697d17ff

精彩文章推荐：

中生代技术

推送有营养的技术干货文章；

总覆盖会员100000+人；资深架构、总监等职位以上3000+人。

定期在线分享超过100期，线下技术沙龙超过70次、覆盖20多个等城市！

关注技术架构、研发管理、互联网金融、电商、大数据、区块链、人工智能等方向！

加入中生代技术群聊，投稿等请添加白明微信：zsdwyq，注明姓名、职称和技术方向，通过后加入中生代技术群，和群友们共同学习成长！